List Public Works

GET /obras

List Public Works

cURL

curl --request GET \
  --url https://api.example.com/obras \
  --header 'Authorization: <authorization>'

200

{
  "data": [
    {
      "id": 123,
      "numeroObra": 123,
      "claveUnica": "<string>",
      "nombre": "<string>",
      "descripcion": "<string>",
      "monto": 123,
      "ejercicioFiscalId": 123,
      "ejercicioFiscal": {},
      "dependenciaId": 123,
      "dependencia": {},
      "municipioId": 123,
      "municipio": {},
      "tipoProyectoId": 123,
      "tipoProyecto": {},
      "estatusObraId": 123,
      "estatusObra": {},
      "ubicaciones": [
        {
          "id": 123,
          "municipioId": 123,
          "direccion": "<string>",
          "localidadReferencia": "<string>",
          "referenciaLugar": "<string>",
          "tipoGeometria": "<string>",
          "geometriaJson": {},
          "orden": 123
        }
      ]
    }
  ],
  "meta": {
    "totalItems": 123,
    "itemCount": 123,
    "itemsPerPage": 123,
    "totalPages": 123,
    "currentPage": 123
  }
}

Retrieves a paginated list of public works (obras) with optional filtering and search capabilities.

Authentication

This endpoint requires a valid JWT token. Both admin and user roles can access this endpoint.

Headers

Authorization · string · required

Bearer token for authentication

Authorization: Bearer YOUR_JWT_TOKEN

Query Parameters

limit · number · default: "10"

Number of obras to return per page. Minimum value: 1.

page · number · default: "1"

Page number to retrieve. Minimum value: 1.

search · string

Search keyword to filter obras by name, description, or unique key (claveUnica). Case-insensitive partial match.

Example: search=Baños

ejercicioFiscalId · number

Filter obras by fiscal year ID.

municipioId · number

Filter obras by municipality ID.

Response

data · array

Array of obra objects

id · number

Unique identifier for the obra

numeroObra · number

Sequential obra number within the fiscal year (auto-generated)

claveUnica · string

Unique key for the obra (max 50 characters)

nombre · string

Name of the public work (max 255 characters)

descripcion · string

Detailed description of the obra

monto · number

Budget amount (decimal with 2 decimal places)

ejercicioFiscalId · number

Fiscal year ID

ejercicioFiscal · object

Fiscal year details object

dependenciaId · number

Department/dependency ID

dependencia · object

Department details object

municipioId · number

Municipality ID

municipio · object

Municipality details object

tipoProyectoId · number

Project type ID (nullable)

tipoProyecto · object

Project type details object

estatusObraId · number

Work status ID

estatusObra · object

Work status details object

ubicaciones · array

Array of location objects associated with this obra

id · number

Location ID

municipioId · number

Municipality ID for this location

direccion · string

Street address

localidadReferencia · string

Locality reference (nullable)

referenciaLugar · string

Place reference (nullable)

tipoGeometria · string

Geometry type: PUNTO, RUTA, or POLIGONO

geometriaJson · object

GeoJSON geometry data

orden · number

Display order

meta · object

Pagination metadata

totalItems · number

Total number of obras in the database matching the filters

itemCount · number

Number of obras returned in this response

itemsPerPage · number

Number of items per page (same as limit parameter)

totalPages · number

Total number of pages available

currentPage · number

Current page number

Example Request

curl -X GET "https://api.yucatan.gob.mx/obras?limit=20&page=1&search=escuela&ejercicioFiscalId=2024" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Example Response

{
  "data": [
    {
      "id": 1,
      "numeroObra": 1,
      "claveUnica": "OBRA-2024-001",
      "nombre": "Construcción de Escuela Primaria",
      "descripcion": "Construcción de escuela primaria con 6 aulas",
      "monto": 2500000.00,
      "ejercicioFiscalId": 1,
      "ejercicioFiscal": {
        "id": 1,
        "anio": 2024,
        "nombre": "Ejercicio Fiscal 2024"
      },
      "dependenciaId": 1,
      "dependencia": {
        "id": 1,
        "nombre": "Secretaría de Obras Públicas"
      },
      "municipioId": 1,
      "municipio": {
        "id": 1,
        "nombre": "Mérida",
        "codigo": "001"
      },
      "tipoProyectoId": 1,
      "tipoProyecto": {
        "id": 1,
        "nombre": "Educación"
      },
      "estatusObraId": 1,
      "estatusObra": {
        "id": 1,
        "nombre": "En Proceso"
      },
      "ubicaciones": [
        {
          "id": 1,
          "municipioId": 1,
          "direccion": "Calle 60 x 59, Col. Centro",
          "localidadReferencia": "Centro",
          "referenciaLugar": "Cerca del parque principal",
          "tipoGeometria": "PUNTO",
          "geometriaJson": {
            "type": "Point",
            "coordinates": [-89.6247, 20.9674]
          },
          "orden": 0
        }
      ]
    }
  ],
  "meta": {
    "totalItems": 150,
    "itemCount": 20,
    "itemsPerPage": 20,
    "totalPages": 8,
    "currentPage": 1
  }
}

Error Responses

401 Unauthorized

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Returned when the JWT token is missing, invalid, or expired.

400 Bad Request

{
  "statusCode": 400,
  "message": [
    "limit must not be less than 1",
    "page must not be less than 1"
  ],
  "error": "Bad Request"
}

Returned when query parameters fail validation.